home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 7 / Apprentice-Release7.iso / Source Code / C / Applications / Moscow ML 1.42 / README.MacDev < prev    next >
Encoding:
Text File  |  1997-07-29  |  10.0 KB  |  267 lines  |  [TEXT/Moml]
  1. Mosml Mac 1.42e  Developers Readme  1997Jul26 e <e@flavors.com>
  2.  
  3. Read README.Mac first if you want to know how to use Moscow ML.
  4.  
  5. Read !README.first about installing the source files.
  6.  
  7. This file describes how to build Mac Moscow ML from the sources.
  8.  
  9. I used Metrowerks CodeWarrior Pro 1 to port Moscow ML 1.42.
  10. The CodeWarrior Pro project files are included.
  11.  
  12. Because mosmlyac and runtime have identically named files in them, I 
  13. found it necessary to rename folder "runtime" to "!runtime" so Metrowerks 
  14. would choose the right files. I could have also solved this problem by 
  15. putting the project files into the runtime folder (as I did by putting the 
  16. mosmlyac project into mosmlyac) but I didn't. Why? I like to debug from the 
  17. Metrowerks debugger and so I want the project to live in the same directory 
  18. as the finished application.
  19.  
  20. I deliberately named the distribution directory mosml142. If you rename the 
  21. linux toplevel folder to mosml142 you can use CompactPro to install the 
  22. .sea files as updates. Without renaming, you can't use Stuffit to obliterate 
  23. the linux files with the update directories. It's my pet peeve, sorry.
  24.  
  25. The directory structure to three levels is as follows:
  26.  
  27. ANSIshellƒ                 -- the eConsole & eEdit sources
  28.    <lots of files>
  29. mosml142
  30.    e_mac                   -- mosml <-> eConsole & MacOS glue
  31.       dirent.h
  32.       e_access.c
  33.       e_cgi_main.c
  34.       e_dirent.c
  35.       e_filelink.c
  36.       e_getenv.c
  37.       e_gettimeofday.c
  38.       e_graph.c
  39.       e_stat.c
  40.       e_system.c
  41.       m.h
  42.       mac_main.c
  43.       mac_os.c
  44.       mac_os.h
  45.       momlmenus.c
  46.       momlmenus.h
  47.       mosml.rsrc
  48.       mosml_cgi.rsrc
  49.       os_mac_cmdmenu.c
  50.       os_mac_options.h
  51.       prims_cgi.c
  52.       rename_patch.c
  53.       s.h
  54.       sys/param.h
  55.       sys/resource.h
  56.       sys/stat.h
  57.       sys/time.h
  58.       sys/times.h
  59.       sys/types.h
  60.       sys/unistd.h
  61.       sys/utsname.h
  62.       ui.h
  63.       uio.c
  64.    e_SML                 -- see the Readme file in that folder
  65.      <a few files>
  66.    lib                   -- the Moscow ML library object code
  67.      <many files>
  68.    lib_extra             -- things to copy to any new lib
  69.      <a few files>
  70.    MacReleaseNotes.txt
  71.    mosml.image           -- toplevel includes make & link
  72.    mosml142.prj          -- CWPro project
  73.    mosml142app           -- ppc application
  74.    mosml142app.lib       -- ppc shared library
  75.    mosml142cgi           -- ppc cgi application
  76.    mosml142cgi.lib       -- ppc cgi shared library
  77.    mosml142m68.sea       -- 68k applications compressed
  78.    mosmllex.image        -- the lexer
  79.    mosmllink.image       -- the linker (redundant)
  80.    MSLpatches            -- source patches to MetroWerks Standard Library
  81.      <a few files>
  82.    README.Mac
  83.    README.MacDev
  84.    src                   -- additions & replacements to the linux source
  85.       !runtime...
  86.       compiler...
  87.       lex...
  88.       mosmllib...
  89.       mosmlyac...
  90.         mosmlyacc.prj    -- CWPro project
  91.         mosmlyacc68k     -- 68k application
  92.         mosmlyaccPPC     -- ppc application
  93.       test...
  94.       tools...
  95.       toolssrc...
  96.  
  97. With all the files in place, the mosml apps and shared libraries can be 
  98. re-built from the sources simply by opening the project file and doing 
  99. a Make. You'll need MetroWerks CodeWarrior Pro. [It may be necessary to 
  100. fix a path for ANSIShellƒ in the Load Paths preferences, but shouldn't.]
  101.  
  102. ** Unfortunately this may not be true if you're using an unpatched version of
  103. CodeWarrior Pro, see the file MSLpatches:Readme.MSL
  104.  
  105. *** Note: There's a bit of pre-processing of the files that in UNIX 
  106. versions of mosml takes place via sed, awk, perl, cpp, etc. All of these 
  107. intermediate files are provided in this Mac version. 
  108. If you have sed, awk, perl, cpp, etc. then you may prefer to grok the 
  109. make scripts and generate these files yourself -- it is safer to do so 
  110. since they are generated from sources independent of this archive.
  111.  
  112. Here are some basic rules:
  113.  
  114. .grm files are processed by mosmlyac, which is supplied. Move mosmlyac 
  115. temporarily to the folder with the .grm file, launch it, type in the .grm 
  116. file name, and that's it. Move mosmlyac back to its folder.
  117.  
  118. .lex files are processed with mosmllex, which is also supplied. The file 
  119. e_SML:make_mosml.sml has a few command lines which can be used with mosml 
  120. to process the .lex files in the usual distribution.
  121.  
  122. .mlp files are processed by cpp, the C pre-processor. I do this by hand 
  123. since the MetroWerks compiler is freaked out by ML syntax.
  124.  
  125. A few other files must be created using sed, awk, and perl. I've supplied
  126. all of these intermediate files since these tools are not widely used on 
  127. the Mac. A few perl droplets are supplied anyway in case you need to redo 
  128. my work. Drop runtime's instruct.h onto mksmlopc to make Opcodes.sml. 
  129. Launch mksmlpre and supply the command line...
  130.   ::!runtime:globals.h ::!runtime:fail.h
  131. to make Predef.sml. Making Prim_c.sml (and prims.c) is harder since it 
  132. first requires making the file "primitives" [which requires sed and awk 
  133. and running a UNIX shell script, if you believe the make file]. Once you 
  134. have primitives [I made mine by hand] you can drop it onto mksmlprc to make 
  135. Prim_c.sml. [Warning: I haven't actually used these perl scripts since
  136. version 1.40, I think. Use at your own risk. I hate perl. -- e]
  137.  
  138. I've also supplied a file make_opcodes.sml that can make Opcodes.sml
  139.  
  140. If you already have the mosml object files in your lib (e.g., from 
  141. the application release), the following step isn't necessary, just 
  142. launch mosml142m68 or mosml142app. This step is only necessary when there 
  143. are no object files in the lib or you have edited the library sources in
  144. src:mosmllib or other src: files...
  145.  
  146. With the existing or new mosml142m68 or mosml142app, you can recreate all 
  147. the mosml object files by following the script in e_SML:make_mosml.sml.
  148. This script compiles all source files in the distribution, creates the 
  149. images for the toplevel and lexer, and copies the new library files to 
  150. a new folder called lib2:. You should manually copy the files in lib_extras 
  151. to lib2, and rename lib2 to lib when you are satisfied with it.
  152.  
  153. The files in lib_extras are derived from the linux sources or are simply 
  154. renamed version of General.fke, Meta.fke in src:mosmllib. There are 
  155. instructions in e_SML:helpsigsmake.mac on how to make the htmlsigs and 
  156. helpsigs.val documentation files.
  157.  
  158. (* *)
  159.  
  160. This section is certainly only of historical interest.
  161.  
  162. Here is some detail about what I have done to make mosml 1.30 work on the 
  163. Mac...
  164.  
  165. I already had The Caml Light 0.7 runtime working on the Mac with my own 
  166. console/editor environment. This code (which I'll call eConsole) 
  167. supplies some of the missing UNIX functions such as timers for user, 
  168. system, and gc, and of course, terminal i/o. Also for Caml Light and 
  169. SML/NJ, I had implemented UNIX -> Mac pathname translation and included 
  170. it in the runtime. This supports using UNIX created images (e.g., 
  171. mosmlcmp) in the Mac environment.
  172.  
  173. So, step one was diff'ing mosml 1.30 and my custom Caml Light 0.7 
  174. runtimes to merge my stuff in. This was not hard; although mosml seems 
  175. to be based on an early 0.7 beta, I got my stuff in easily. A few 
  176. changes were required for the MetroWerks 68k compiler. I  also added in 
  177. my user, system, and gc timer.
  178.  
  179. Then I created replacements for some of the missing UNIX functions. 
  180. These include access, readdir, etc. I also made several files such as 
  181. "sys/unistd.h" that are simply one line: #include <unistd.h>. This makes 
  182. modification of the mosml sources that include "sys/xxx.h" files 
  183. unnecessary. It also makes a convenient place to put special unixfoolery 
  184. such as defining F_OK, and overriding MWERKS flawed implementations, 
  185. e.g., of chdir.
  186.  
  187. It was also necessary to add a couple macros to mosml.c to adjust the 
  188. Mac time (1904 base) to UNIX time (1970 base) and back.
  189.  
  190. Then I could compile and link the world. I did this one file at a time. 
  191. [Now that I have made make, this will never again be necessary!?]
  192.  
  193. The SML changes I made were few.
  194.  
  195. In mosmllib I hooked in my gc timer (UNIX and DOS don't have one), I 
  196. hooked in osInfo (sml_uname), and fixed or worked around a couple bugs 
  197. [these are now reported/fixed]. The changed files are:
  198.  
  199. Mosml.sml  gc timer
  200. Timer.sml  gc timer
  201. OS.sml     sml_uname (should be changed: OS.mlp)
  202.  
  203. FileSys.sml  -- I used the DOS version at first, then custom
  204. Path.sml     -- I used the UNIX version at first, then custom
  205.  
  206. and these files which, I think, are equivalent to what cpp would have 
  207. done:
  208.  
  209. Array.sml
  210. Integer.sml
  211. Strbase.sml
  212. Vector.sml
  213. Word.sml
  214. Word8Array.sml
  215. Word8Vector.sml
  216.  
  217. In compiler I changed:
  218.  
  219. Smltop.sml   to add chDir and gc_full_major
  220. Link.sml     to make missing_globals a ref
  221. Symtable.sml to add protect_linker_tables
  222. Symtable.sig to make this visible
  223.  
  224. The purpose of the linker changes is twofold. In order to do a link in a 
  225. toplevel environment it is necessary to save and restore the current 
  226. environment. All the effected data are in the Symtable unit [as I said 
  227. above, this isn't well tested]. protect_linker_tables was added to 
  228. this job. The second part of the change in to make missing_globals a 
  229. ref. This change was also made by INRIA at my request in Caml Light. 
  230. This is needed because the missing_globals hashtable gets very big for 
  231. some links, and never shrinks. In fact is seems to get bigger with 
  232. every link. To conserve memory the new link disposes the table after 
  233. every link.
  234.  
  235. I also created:
  236.  
  237. Opcodes.sml
  238. Predef.sml
  239. Parser.sig
  240. Parser.sml
  241. Filename.sml
  242. Config.sml
  243. Lexer.sml
  244.  
  245. from the requisite sources.
  246.  
  247. Then I added the new sources for Smltope and Maine.
  248.  
  249. The only files I changed in runtime are:
  250.  
  251. mosml.c      Mac <-> UNIX time, e_getrusage
  252. floats.c     used Caml Light 0.7 version (has my compiler fixes)
  253. misc.c       kill bogus malloc prototype
  254. minor_gc.c   gc timer
  255. major_gc.c   gc timer
  256. misc.h       includes <stdlib.h> for malloc bug
  257. prims.c      generated file
  258. main.c       [I don't remember,  I'll diff it later]
  259. interp.c     punt spin (it's in ui.h)
  260. fail.c       #define MAXDOUBLE
  261. config.h     MWERKS friendly m.h & s.h includes
  262. sys.c        UNIX -> Mac pathname translation
  263.  
  264. I also added a bunch of new files for eConsole and unixfoolery.
  265.  
  266. e
  267.